docs: Update Workflows page #6648
Conversation
✅ Deploy Preview for nextflow-docs-staging ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
I see the logic in having all of this stuff together. My instinct here is that I think the page would benefit from a stronger overview at the top, i.e., a list of major parts (entry, parameters, outputs, named workflows, dataflow) with one-line descriptions and an explanation that all of this is related under the concept of a workflow, with a reasonably simple example showing these parts. This probably softens the need for the order to be perfect, as everything is already framed rather than being progressive information. I'll vibe a PR to see how it looks in this scenario. |
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
bentsherman
force-pushed
the
docs-workflow-page
branch
from
682c69d to
fc7bcae
Compare
|
@christopher-hakkaart I tried my hand at an overview for the Workflows page, let me know what you think |
christopher-hakkaart
left a comment
christopher-hakkaart
left a comment
There was a problem hiding this comment.
Overall, I like the direction and changes. I would like to take a pass at this, but I'm tied up with other projects for the next couple of weeks and won't have time to give it the attention it deserves. This is a significant improvement, and I would suggest mostly language changes rather than rearranging sections. I don't want to hold this up.
My main suggestions are to add a list of the main sections and minimal descriptions that are scannable rather than sentences and add a bit more context/description at the start of sections to help frame the section.
Take or leave what you like/dislike.
I started some consistency suggestions, but they probably aren't worth it until the whole page is standardized, which I can follow up with in a second PR.
docs/workflow.md
Outdated
| In Nextflow, a **workflow** is a function that is specialized for composing {ref}`processes <process-page>` and dataflow logic: | ||
|
|
||
| See {ref}`syntax-workflow` for a full description of the workflow syntax. | ||
| - An [entry workflow](#entry-workflow) is the entrypoint of a pipeline. It can take [parameters](#parameters) as inputs using the `params` block, and it can publish [outputs](#outputs) using the `output` block. | ||
|
|
||
| :::{note} | ||
| Workflows were introduced in DSL2. If you are still using DSL1, see {ref}`dsl1-page` for more information about how to migrate your Nextflow pipelines to DSL2. | ||
| ::: | ||
| - A [named workflow](#named-workflows) is a workflow that can be called by other workflows. It can define its own inputs and outputs, which are called *takes* and *emits*. | ||
|
|
||
| - Both entry workflows and named workflows can contain [dataflow logic](#dataflow) such as calling processes, workflows, and channel operators. |
There was a problem hiding this comment.
| In Nextflow, a **workflow** is a function that is specialized for composing {ref}`processes <process-page>` and dataflow logic: | |
| See {ref}`syntax-workflow` for a full description of the workflow syntax. | |
| - An [entry workflow](#entry-workflow) is the entrypoint of a pipeline. It can take [parameters](#parameters) as inputs using the `params` block, and it can publish [outputs](#outputs) using the `output` block. | |
| :::{note} | |
| Workflows were introduced in DSL2. If you are still using DSL1, see {ref}`dsl1-page` for more information about how to migrate your Nextflow pipelines to DSL2. | |
| ::: | |
| - A [named workflow](#named-workflows) is a workflow that can be called by other workflows. It can define its own inputs and outputs, which are called *takes* and *emits*. | |
| - Both entry workflows and named workflows can contain [dataflow logic](#dataflow) such as calling processes, workflows, and channel operators. | |
| A **workflow** composes {ref}`processes <process-page>` and dataflow logic to define how data flows through your pipeline. A Nextflow script typically includes: | |
| - **[Entry workflow](#entry-workflow)**: A main entrypoint that orchestrates the pipeline | |
| - **[Parameters](#parameters)**: Configurable inputs | |
| - **[Outputs](#outputs)**: Published results | |
| - **[Named workflows](#named-workflows)**: Reusable workflow components that can be called by other workflows | |
| - **[Dataflow](#dataflow)**: Channels and operators connecting processes | |
| For detailed syntax and usage instructions, see {ref}`syntax-workflow`. |
IMO - these are relatively novel concepts for a new user, a high-level list of what each part is that can be scanned helps frame the page.
|
|
||
| ## Parameters | ||
|
|
||
| Parameters can be declared in a Nextflow script with the `params` block or with *legacy* parameter declarations. |
There was a problem hiding this comment.
| Parameters are configurable variables that control pipeline behavior. You can declare parameters with [typed parameters](#typed-parameters) in the `params` block or with [legacy parameters](#legacy-parameters) to customize pipeline behavior at runtime. |
|
I started working on a PR here before the holidays: https://github.com/christopher-hakkaart/nextflow/tree/chris-docs-workflow-page |
Signed-off-by: Ben Sherman <[email protected]>
This PR re-organizes the documentation on workflows and dataflow logic to match the current Nextflow programming model.
Move "Outputs" to the top after "Entry workflow" and "Parameters" to emphasize that these three things go together
Move "Dataflow" page into the "Workflows" page as a section after "Entry workflow" and "Named workflows", since dataflow logic exists primarily in the context of a workflow
Move auxiliary sections (calling processes, special operators, recursion) under "Dataflow", since all of these concepts fall under the umbrella of dataflow logic
I'm open to different ordering / structuring. I just think all of this content goes together